-
-
Notifications
You must be signed in to change notification settings - Fork 920
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: consistent @see jsdoc tags #2473
Conversation
Codecov Report
Additional details and impacted files@@ Coverage Diff @@
## next #2473 +/- ##
==========================================
- Coverage 99.57% 99.57% -0.01%
==========================================
Files 2805 2805
Lines 250088 250093 +5
Branches 1100 1098 -2
==========================================
- Hits 249031 249028 -3
- Misses 1029 1037 +8
Partials 28 28
|
Co-authored-by: DivisionByZero <[email protected]>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There's quite a lot of inconsistency in the phrasing like:
- If you wish to generate foo
- If you would like to generate foo
- For a method that returns foo
- To generate foo
Here are all `@see` Tags@see faker.company.name(): For a method that returns a complete company name.
@see faker.date.anytime(): For the new method when generating a random date in either the past or future.
@see faker.date.between(): For dates in a specific range.
@see faker.date.between(): For the new method when generating a random date in between two dates.
@see faker.date.future(): For dates explicitly in the future.
@see faker.date.future(): For dates further in the future (years instead of days).
@see faker.date.past(): For dates explicitly in the past.
@see faker.date.past(): For dates further back in time (years instead of days).
@see faker.date.recent(): For dates in the recent past (days instead of years).
@see faker.date.soon(): For dates in the near future (days instead of years).
@see faker.finance.accountNumber(): For the new method that replaces this one.
@see faker.finance.maskedNumber(): For the new method that replaces this one.
@see faker.helpers.fromRegExp(): Generates a string matching the given regex like expressions.
@see faker.helpers.mustache(): For more information about how the phrases are generated.
@see faker.helpers.mustache(): If you wish to use custom functions for resolution.
@see faker.helpers.replaceCreditCardSymbols(): For more information about how the pattern is used.
@see faker.helpers.replaceSymbolWithNumber(format): For more information about how the patterns are used.
@see faker.helpers.replaceSymbols(): For more information about how the pattern is used.
@see faker.image.url(): To generate a random image url (has less options, but doesn't break when LoremFlickr is removed).
@see faker.image.urlLoremFlickr(): To generate a random image url from LoremFlickr.
@see faker.internet.displayName(): If you wish to generate a Unicode display name.
@see faker.internet.userName(): If you wish to generate a plain ASCII username.
@see faker.location.city(): For the new method that replaces this one.
@see faker.location.street(): For the new method that replaces this one.
@see faker.location.zipCode(): For the new method that replaces this one.
@see faker.lorem.word(): To generate a random placeholder word.
@see faker.lorem.words(): To generate a sequence of random placeholder words.
@see faker.number.bigInt(): For the new method when generating a random bigint.
@see faker.number.binary(): If you would like to generate a `binary number` (within a range).
@see faker.number.float(): For the new method when generating a random floating-point number.
@see faker.number.hex(): For the new method when generating a random hexadecimal number.
@see faker.number.int(): For the new method when generating a random integer.
@see faker.number.int(): If you would like to generate a `number` (within a range).
@see faker.number.octal(): If you would like to generate an `octal number` (within a range).
@see faker.person.gender(): If you would like to generate gender related values.
@see faker.person.gender(): If you would like to use the gender value in forms.
@see faker.person.sex(): If you would like to generate binary-gender values.
@see faker.person.sex(): If you would like to use the sex value in forms.
@see faker.person.sexType(): If you would like to use the sex value as a parameter.
@see faker.seed(): If you wish to generate reproducible values.
@see faker.setDefaultRefDate(): If you wish to generate reproducible dates.
@see faker.setDefaultRefDate(): If you wish to generate reproducible relative dates.
@see faker.string.alpha(): For the new method replacing this one.
@see faker.string.alphanumeric(): For the new method replacing this one.
@see faker.string.binary(): If you would like to generate a `binary string` with a given length (range).
@see faker.string.hexadecimal(): For the new method when generating a random hexadecimal string.
@see faker.string.numeric(): For the new method replacing this one.
@see faker.string.numeric(): If you would like to generate a `string` of digits with a given length (range).
@see faker.string.octal(): If you would like to generate an `octal string` with a given length (range).
@see faker.string.sample(): For the new method when generating a random string.
@see faker.string.uuid(): For the new method when generating a random UUID.
@see faker.word.sample(): To generate a random existing word.
@see faker.word.words(): To generate a sequence of random existing words.
@see mergeLocales() For more information about how the locales are merged. Any suggestion on how to simplify them to a few patterns? We probably need at least two:
|
As a first step we can replace "If you would like to generate" and "If you wish to generate" and "To generate" with "For generating" |
If its an identical replacement method (just a rename, no parameter/behavior changes) i think we could standardise on "For the replacement method" |
Fixes #2057
Requires that all
@see
tags that point to faker methods follow the following pattern:@see faker.<module>.<method>(.*): [A-Z]___.
All changes are in a single PR to make it easier to cross compare the individual changes.
Feedback and re-phrasing suggestions welcome.